Review — PR #830 (Agent Map 11/15, focused context)

No confidentiality issues: the changeset, docs/shared-build-plan.md, tests, and the
stock-research-compile.golden.json fixture are role-neutral, digest-only, and name no company.

Findings

1. Derived brief requestId shares a namespace with caller-supplied ones — permanently poisonable

agent-map-mcp-tools.ts:279 and :300 derive requestId: \brief-${result.plan.versionId}`, but build_plan_brief_refreshlets the caller pass anyopaquestring asrequestId (build-plan-schema.ts:55` — no reserved-prefix check). Reachable sequence, all from one session:

1. Plan is at planv_X. Agent calls build_plan_brief_refresh with
   requestId: "brief-planv_X" and focus: {mode:"focused", …} → receipt stored under that id
   with the focused-mode request digest.
2. Agent calls build_plan_apply with unchanged content → noOp, result.plan.versionId is still
   planv_X (build-plan-service.ts:446,584) → derived requestId is brief-planv_X, focus
   canonical → different requestDigest → AgentBriefService.replay throws request_id_reused
   (agent-brief-service.ts:234).

The catch turns that into briefRefresh: { outcome: "retryable" }, and every later no-op
apply/rebase at planv_X fails identically, so canonical briefs never refresh for that plan
version. Version ids are handed to the agent in every tool result, so this is not an exotic input.
Fix: namespace the derived id out of the caller's reach (e.g. reject a caller requestId matching
^brief-planv_, or derive from a digest the caller cannot reproduce).

2. briefRefreshFailure reports non-retryable errors as retryable

agent-map-mcp-tools.ts:128-135 maps everything except quota_exceeded to retryable. The
standalone tool's own errorResult (:105-110) correctly maps request_id_reused/
request_id_expired → new_request, source_mismatch → reread, malformed_input → correct.
So the same error class gets contradictory recovery advice depending on the entry point, and an
agent that obeys retryable re-runs apply — which regenerates the identical deterministic
requestId and fails the same way. Reuse the errorResult recovery mapping here.

3. Public surface widened at minor with a path consumers cannot use

src/index.ts now exports AgentBriefService, DeterministicAgentBriefCompiler,
compileAgentBriefs, compileCanonicalWorkstreamBriefs, projectFocusedBriefs,
evaluateAgentBriefImpact, serializeFocusedSessionContext, FocusedSessionContextProjection
and 5 constants. Nothing in the repo imports any of them from the package — not the CLI, not
harness-desktop, not web/src (only public-build-plan-entrypoint.test.ts touches one
constant). More concretely, the workflow docs/shared-build-plan.md documents — "passing the
branded projection through TrustedSessionCreateOptions or TrustedSessionResumeOptions" — is
unreachable: SessionManager and both option types are not exported from src/index.ts
(only ensureSpawnHelperExecutable is, index.ts:90). So the branded type ships publicly while
the only API that accepts it does not. Either export the consuming surface in the same increment
or keep the compiler/service/serializer internal until the increment that activates them; every
name here is a permanent contract once published. compileAgentBriefs is additionally a
third alias for projectFocusedBriefs (agent-brief-compiler.ts:719) with no prior published
name to stay compatible with — drop it. The changeset should also list the added exports
(harness CLAUDE.md checklist).

4. Compiler diagnostics point at the wrong selections[i]

agent-brief-compiler.ts:572 iterates sorted(request.selections, …).entries(), then emits
selections[${selectionIndex}].focusScope (:576) and selections[${selectionIndex}].mission
(:639) using the sorted index. A caller submitting selections in any order other than
scope-key order gets a diagnostic path naming a different selection than the one that failed.
Carry the original index alongside the sorted entry.

Verdict

Request changes: fix (1) and (2) before merge — both are agent-facing correctness bugs in the new
build_plan_apply/rebase refresh path. (3) is the call to make now rather than after publish.
Test coverage for the compiler, projection redaction/escaping, quota exhaustion and compiler-failure
isolation is solid; AgentBriefService has no direct unit test but is well covered through
agent-map-mcp.test.ts.

Follow-up review — PR #830 (delta since 67664734)

Two commits landed: bf3dcf78 (reserved receipt namespace, recovery mapping, selection
indices) and 662edabb (two more public exports). No confidentiality issues in the new
prose — the changeset, docs/shared-build-plan.md and the new tests stay role-neutral.

Earlier findings — status

• (1) derived brief requestId poisonable — fixed. harness-internal:brief: is now
  reserved via isCallerProjectRequestId on all four writer schemas that land in
  requestReceipts (brief refresh, plan apply, plan rebase, proposal batch), and the
  derived id moved into refreshAfterPlanMutation. I re-checked the residual collision I
  expected inside the reserved namespace — a no-op mutation reusing a plan versionId under
  a different map — and it is unreachable: apply only reports noOp when
  current.map === expectedMap (build-plan-service.ts:465) and rebase only when
  fromMap === toMap (:573), so the digest is stable per plan version.
• (2) briefRefreshFailure mislabelling non-retryable errors — fixed. It now derives
  from errorResult, and agent-map-mcp.test.ts pins all five recovery outcomes.
• (4) diagnostics pointing at the sorted index — fixed, with a regression test.
• (3) public surface widened with no consumer — NOT fixed; widened further.
  662edabb adds PROJECT_AGENT_PROMPT_APPENDIX and projectAgentPromptAppendix to
  src/index.ts; nothing outside the package imports either (only relative imports in
  server/index.ts and tests), and the first pins the literal system-prompt text as a
  semver-stable constant. compileAgentBriefs is still a third alias for
  projectFocusedBriefs and the docs now call it "supported", making it permanent.
  Exporting AgentBriefService also hands external code refreshAfterPlanMutation, the
  trusted hook that writes into the reserved namespace the changeset says callers cannot
  occupy. The docs were corrected honestly (session controls "are not package exports"),
  but the changeset still does not list the two new prompt exports.

Verdict

The two agent-facing correctness bugs are genuinely fixed. Finding (3) stands and the
follow-up commit moved the wrong way — trim the exports to what a host actually needs
before this publishes.